Create an Execution Task (sys.task)
Declaration
task = sys.task(executable_path [, arguments...])
Parameters
- executable_path
String - arguments...
String, optional variadic arguments, defaults to none
Return Value
- task
Execution task object, returns an object for controlling or executing the task
Task Object Methods
| Method | Parameters | Return Value | Description |
|---|---|---|---|
| :launch() | Launch the task, runs asynchronously | ||
| :wait_until_exit() | Synchronously wait for task to finish, blocks all threads until task ends. | ||
| :set_stdin(input_stream) | Pipe | String | Set the task's input stream. Parameter can be "std", "/dev/null", a file path, or a pipe object. Throws an error if called after task is launched | |
| :stdin() | Pipe | String | Get the task's input stream. May return "std", "/dev/null", a file path, or a pipe object | |
| :set_stdout(output_stream) | Pipe | String | Set the task's output stream. Parameter can be "std", "/dev/null", a file path, or a pipe object. Throws an error if called after task is launched | |
| :stdout() | Pipe | String | Get the task's output stream. May return "std", "/dev/null", a file path, or a pipe object | |
| :set_stderr(error_stream) | Pipe | String | Set the task's error stream. Parameter can be "std", "/dev/null", a file path, or a pipe object. Throws an error if called after task is launched | |
| :stderr() | Pipe | String | Get the task's error stream. May return "std", "/dev/null", a file path, or a pipe object | |
| :set_work_dir(directory) | String | Set the task's working directory. Throws an error if called after task is launched | |
| :work_dir() | String | Get the task's working directory | |
| :set_env(environment_variables) | Table | Set the task's environment variable key-value dictionary. Throws an error if called after task is launched | |
| :env() | Table | Get the task's environment variable key-value dictionary | |
| :pid() | Integer | Get the task's process ID, returns 0 if task has not been launched | |
| :is_running() | Boolean | Check if the task is running. Even if :is_running() returns false, you should still call :wait_until_exit() once on the task to prevent zombie processes | |
| :interrupt() | Boolean | Send SIGINT signal to the task's main process | |
| :terminate() | Boolean | Send SIGTERM signal to the task's main process | |
| :kill() | Boolean | Send SIGKILL signal to all processes of the task, kill operation is automatically executed when the task object is garbage collected | |
| :termination_status() | Integer | Get the task's termination status, returns nil, error_message if task has not ended | |
| :termination_reason() | String | Get the task's termination reason, returns nil, error_message if task has not ended |
Pipe Object Methods
| Method | Parameters | Return Value | Description |
|---|---|---|---|
| :read() | String | Read available data from the pipe | |
| :write(data) | String | Write data to the pipe | |
| :wclose() | Boolean, nil | String | Close the write end of the pipe, returns true on success, false, error_message on failure | |
| :rclose() | Boolean, nil | String | Close the read end of the pipe, returns true on success, false, error_message on failure |
Description
Creates an execution task and returns an execution task object
If you don't want to block all threads waiting for the task, you can loop using the task object's:is_running()to check if the task is running. Once it's no longer running, you can call:wait_until_exit()once to confirm the task has ended
Available in versions after 2025-07-05.
Example
-- Simulate the following Shell command
-- echo "Hello World" | /usr/bin/gzip -fc | /usr/bin/gzip -dfc
local comp_tsk = sys.task(jbroot('/usr/bin/gzip'), '-fc') -- Create compression task
local decomp_tsk = sys.task(jbroot('/usr/bin/gzip'), '-dfc') -- Create decompression task
decomp_tsk:set_stdin(comp_tsk:stdout()) -- Set decompression task's input stream to compression task's output stream
decomp_tsk:launch() -- Launch decompression task
comp_tsk:launch() -- Launch compression task
comp_tsk:stdin():write("Hello World") -- Write data to compression task's input stream
comp_tsk:stdin():wclose() -- Close compression task's input stream write end, indicating input is complete
comp_tsk:wait_until_exit() -- Wait for compression task to finish
decomp_tsk:wait_until_exit() -- Wait for decompression task to finish
nLog(decomp_tsk:stdout():read()) -- Read decompression task's output stream, outputs "Hello World"
Example (Invoke TrollStore Persistence Helper Refresh)
local persistence_helper_path = app.bundle_path('com.apple.tips')
if not persistence_helper_path then
nLog('Tips.app not detected, please install the Tips app from AppStore first')
return
end
local root_helper_path = persistence_helper_path..'/trollstorehelper'
if file.exists(root_helper_path) ~= 'file' then
nLog('TrollStore Persistence Helper not injected into Tips, please go to TrollStore -> Settings -> Install Persistence Helper and select Tips to inject')
return
end
local tsk = sys.task(root_helper_path, 'refresh')
tsk:launch()
tsk:wait_until_exit()
sys.killall(9, 'SpringBoard', 'backboardd')
Example (Use TrollStore to Install/Uninstall Apps, Rebuild Icon Cache)
local function _trollstorehelper(...)
local troll_path = app.bundle_path('com.opa334.TrollStore')
assert(type(troll_path) == 'string', 'TrollStore needs to be installed.')
local tsk = sys.task(troll_path..'/trollstorehelper', ...)
tsk:set_stdin('/dev/null')
tsk:launch()
local outbuf = {}
local errbuf = {}
local function drain_stream(stream, buf)
local data = stream:read('nb')
if data and #data > 0 then
buf[#buf + 1] = data
end
end
while tsk:is_running() do
drain_stream(tsk:stdout(), outbuf)
drain_stream(tsk:stderr(), errbuf)
sys.msleep(100)
end
tsk:wait_until_exit()
drain_stream(tsk:stdout(), outbuf)
drain_stream(tsk:stderr(), errbuf)
if tsk:termination_status() == 0 then
local ret = table.concat(outbuf)
return ret
else
local ret = table.concat(errbuf)
return nil, ret
end
end
--- Install an App using TrollStore
---@param ipapath string Path to the installation package
---@return string? Installation result text, returns nil on failure
---@return string? Error message, returns nil on success
function troll_install(ipapath)
return _trollstorehelper('install', ipapath)
end
--- Uninstall an App installed by TrollStore
---@param bid string App bundle identifier
---@return string? Uninstallation result text, returns nil on failure
---@return string? Error message, returns nil on success
function troll_uninstall(bid)
return _trollstorehelper('uninstall', bid)
end
--- TrollStore rebuild icon cache, may take some time
---@return string? Rebuild result text, returns nil on failure
---@return string? Error message, returns nil on success
function troll_rebuild_icon_cache()
return _trollstorehelper('refresh-all')
end
-- Example calls
nLog(troll_install(XXT_SCRIPTS_PATH..'/TrollDecrypt.tipa')) -- Install TrollDecrypt
nLog(troll_uninstall('com.fiore.trolldecrypt')) -- Uninstall TrollDecrypt
nLog(troll_rebuild_icon_cache()) -- Rebuild icon cache